home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / e / bumpee1_44.lha / Bumpee.doc < prev    next >
Encoding:
Text File  |  1995-01-07  |  5.1 KB  |  159 lines
  1.  
  2.          Bumpee 1.44 © 1995 by Leon Woestenberg (leon@stack.urc.tue.nl)
  3.  
  4.        Smart revision bumper for your Amiga E v3.1+ compiled executables
  5.  
  6.  
  7. Distributability
  8. ----------------
  9.  
  10.   Bumpee is freely distributable software. The archive must be copied as a
  11. whole. The source code in the archive may be used to recompile the program,
  12. however do not distribute altered or unaltered recompilations under the
  13. name Bumpee. So, this is NOT public domain.
  14.  
  15. Introduction
  16. ------------
  17.  
  18.   Bumpee is a simple-to-use revision control program for your E sources.
  19. The use of a standarized versionstring, introduced by Commodore-Amiga with
  20. AmigaOS 2.04, offers a neat way to keep track of the executables generated
  21. during program development. An example versionstring looks like this:
  22.  
  23. $VER: Bump 1.0 (6.1.94)
  24.  
  25. which contains the name, version, revision and compilation date of the
  26. executable this string can be found in (the Bumpee tool itself here).
  27. AmigaOS programs like the 'version' command and the 'Installer Utility'
  28. reside on the versionstring inside your program executables.
  29.  
  30. The Concept
  31. -----------
  32.  
  33.   Bumpee uses a standard E module that must be included in your compiled
  34. program, that has a '_rev' suffix. For example, 'Bumpee_rev.m' for Bumpee.
  35. This module offers you several constants that can be used throughout
  36. your source (modules). If you include this module using:
  37.  
  38. MODULE '*<programname>_rev'
  39.  
  40. you have the following constants at your availability:
  41.  
  42. VERSION
  43. REVISION
  44. VERSION_DAY
  45. VERSION_MONTH
  46. VERSION_YEAR
  47.  
  48. in your E source. Apart from this, your executable will automagically
  49. contain the versionstring in a Commodore-Amiga compliant way. You can
  50. check the version of a program using the 'Version' command found in C:.
  51.  
  52. If you also switch on the macro preprocessor of EC, like this:
  53.  
  54. OPT PREPROCESSOR
  55.  
  56. you have an additional two macros at your disposal:
  57.  
  58. VERSION_STRING
  59. VERSION_INFO
  60.  
  61. of which the first macro will be equivalent to the complete version string.
  62. The second macro is the same, but has no '$VER:' header. This one is
  63. particularly handy to use in 'About...' requesters or shell output.
  64.  
  65.   More specific: These macros are stringpointers and NOT typed strings. This
  66. will keep your executables small, even if you use the macros multiple times.
  67.  
  68. Invoking Bumpee
  69. ---------------
  70.  
  71.   Bumpee has the following AmigaDOS template:
  72.  
  73. NAME/A,FORCE/S,BUMPVERSION/S,DONOTCOMPILE/S,ECFILEPATH/K
  74.  
  75. NAME/A
  76.  
  77.   The e source filename to be compiled (NOT the '_rev.e' file), either
  78. with or without the '.e' suffix.
  79.  
  80. CREATE=FORCE/S
  81.  
  82.   This forces to bump always, even if Bumpee thinks a bump is not
  83. appropriate (i.e. when the last program compilation failed, or when no
  84. bumpfile exists for this e source).
  85.  
  86. You would usually set this switch one time to create the bumpfile, and
  87. never use it again on the same source, to let Bumpee decide whether to
  88. jump or not.
  89.  
  90. Also, if you don't have a battery back-upped clock, you would want to
  91. FORCE bumps, as Bumpee otherwise would act on invalid creation dates.
  92.  
  93. BUMPVERSION/S
  94.  
  95.   Bump to a new version. Instead of bumping the revision number, the version
  96. number is increased, and the revision number is reset to zero.
  97.  
  98.   You only need to set this switch on a major version bump, as revisions are
  99. automagically bumped if necessary.
  100.  
  101. DONOTCOMPILE/S
  102.  
  103.   Keeps Bumpee from compiling the revision module.
  104.  
  105.   You only want to set this switch if you want the build utility (that
  106.   compiles the dependancies, under which the revision module) to compile the
  107.   revision module.
  108.  
  109. ECFILEPATH/K
  110.  
  111.   Path and filename of the E Compiler. The E Compiler is used to compile the
  112. revision module. The default path is 'EC', that will work normally if the E
  113. compiler is called 'EC', and resides in a search path directory.
  114.  
  115. Bumpee Usage
  116. ------------
  117.  
  118.   Bumpee must be called prior to compilation of your source. If you
  119. want to create a bumpfile for a fresh e source, use the CREATE switch.
  120.  
  121.   If a compiled executable was already present, its date is checked against
  122. that of the revision module. If the executable's date is later than the
  123. module's date, the last compilation is succeeded and a bump is needed.
  124. Otherwise, when the last compilation seems to have failed, the revision
  125. module is not bumped, as the current revision has not been compiled yet.
  126.  
  127.   The example sources may clear things up a bit.
  128.  
  129. Requirements
  130. ------------
  131.  
  132. · Any Amiga running AmigaOS 2.04 or above.
  133. · Amiga E (© by Wouter van Oortmerssen) would be nice.
  134. · A battery back-upped clock is very handy, as Bumpee becomes smart by
  135.   looking at file creation dates. However, the FORCE option can be used
  136.   to switch off smartness, and therefore the need of a valid clock time.
  137.  
  138. Future
  139. ------
  140.  
  141.   For me, Bumpee is quite finished. However, if you come up with a
  142. splendid idea for a new feature, let me know. If I think it's splendid too,
  143. it may even be implemented :).
  144.  
  145.   If you, as a Bumpee user and E programmer, want to change or add things,
  146. feel free to do so. However, do not spread your own alternations under the
  147. name 'Bumpee', please. Instead, make up a pretty unique name.
  148.  
  149. About the author
  150. ----------------
  151.  
  152.   Die-hard Amiga E programmer (and sometimes inline coder :-), reachable
  153. via email at leon@stack.urc.tue.nl.
  154.  
  155.   Have fun, Leon Woestenberg.
  156.  
  157.  
  158.  
  159.